eDocs Home > BEA AquaLogic Data Services Platform Documentation > Data Services Developer's Guide > Contents

How To Update Physical Data Service Metadata

When you first create a physical data service its underlying metadata is, by definition, consistent with its data source. Over time, however, your metadata may become "out of sync" for several reasons:

• The structure of underlying data sources may have changed, in which case it is important to be able to identify those changes so that you can determine when and if you need to update your metadata.
• You have modified schemas or added relationships to your data service.

In some cases relationships between data services will be preserved during metadata update. See Using the Update Source Metadata Wizard, for details.

Topics

In Project Explorer you can use the right-click menu option Update metadata to see if there are any differences between your source metadata files and the underlying source.

Update Metadata Option in Project Explorer

The Update metadata option can be used with:

• Relational table and view associated with changes to the relational database including providerID, the sourceBindingProviderClassName, columns, and optimistic locking fields.
• Web services
• Java functions 
• Delimited files

Metadata update cannot be applied to data services based on:

• Relational stored procedures
• XML files

Scope of Metadata Update

When you run the Metadata update option, differences between your physical data service and the underlying data source are categorized according to the following scheme:

Category	Meaning
Objects added	The data source contains one or more objects that are not currently represented in the physical data service. From the perspective of the data source, information from the existing data service is added back after the metadata update. Another way to look at this is from the perspective of the data service. In this view, certain artifacts are retained. A typical example is a relationship with another data service. Existing relationships are identified and retained, the metadata is updated to reflect the current data source, and the relationships are added back to the data service.
Objects deleted	One or more objects in the physical data service is not found in the underlying data source. A typical artifact that will be marked for deletion would be a schema that is referenced by an operation (such as a relationship function) in the data service. Objects marked for delete generally appear together. You should carefully inspect the update wizard for items marked for deletion. In the case of schemas, in particular, a prudent course of action would be to retain the schema (uncheck the delete option) unless you are certain that it is not needed by an operation in your data service. Deleting a needed schema will make your data service invalid and undeployable.
Objects changed	One or more objects in the physical data service and the underlying data source do not match and an adjustment will be made. An example of an artifact that will be marked as changed would be if the relational providerID underlying the data source has changed or is unavailable.
Source unavailable	The data source underlying the physical data service could not be accessed.

If there are no differences between your metadata and the underlying source, the Update metadata wizard will report up-to-date for each data service being verified.

In the case of an unavailable data source, the issue likely relates to connectivity or permissions. In the case of the other types of discrepancies, you need to determine when and if to update data source metadata to conform with the underlying data sources.

Important Considerations When Updating Source Metadata

The update metadata operation can have both direct and indirect consequences.

Source metadata should be updated with care by someone who is quite familiar with the underlying data source. For example, if you have added a relationship between two physical data services, updating your source metadata may remove the relationship from both data services. If the relationship appears in a model diagram, the relationship line will appear in red, indicating that the relationship is no longer described by the respective data services.

Direct and Indirect Effects

Direct effects apply to physical data services. Indirect effects occur to logical data services, since such services are themselves based — at least indirectly — on physical data services.

For example, if you have created a new relationship between a physical and a logical data service (not a recommended practice), updating the physical data service can invalidate the relationship. In the case of the physical data service, there will be no relationship reference. The logical data service will retain the code describing the relationship but it will be invalid if the opposite relationship notations is no longer be present.

Using the Update Source Metadata Wizard

The Update metadata wizard allows you to update your source metadata.

Before attempting to update source metadata you should make sure that your build project has no errors.

You can perform a metadata update on your entire dataspace project, folders from the project, or any qualified data service. Generally speaking, metadata updates should be performed as specifically as possible.

Use Shift-click or Ctrl-click to select multiple data services or folders in a single dataspace.

After you select your target(s), the wizard identifies the metadata that will be verified and any differences between your metadata and the underlying source.

You can select/deselect any data service listed in the dialog using the checkbox to the left of the name. You can also choose to select/deselect specific changes for the data service using the checkbox to the left of the change description.

The following screen capture is from a Update Metadata command for the ElectronicsWS project in the sample application.

Details related to the changes that will be made when the metadata is updated appear in the lower panel of the window.

Original Source and Refactored Source Details

The upper portion of the Update metadata plan shows the changes to be performed. In some cases items are presented and selected (checked). In other cases items are presented but unchecked.

In the details view, the left-hand side shows the current source (called Original Source). The right-hand side shows what the result will be after metadata update (called Refactored Source).

Your only options in the dialog are to select or deselect specific changes using the adjacent checkboxes.

Up/down arrows are available on the Update Metadata titlebar to move through the possible changes. (The Filter Changes option icon next to the arrows is not applicable to metadata update and is not active.

Update Metadata Wizard Navigation Arrows

Inspecting and Reverting Changes Using Local History

You can use the Local History option provided with Eclipse to review changes that have been made through the Metadata Update Wizard.

Here are the steps involved:

1. In the Project Explorer right-click on your data service.
2. Select:

   Compare With > Local History...

   The Compare With Local History window will open. If there have been several changes made, each will be identified through a timestamp. 

It is also often possible to revert a metadata update using a similar mechanism:

1. In the Project Explorer right-click on your data service.
2. Select:

   Replace With > Local History...

   The Replace With Local History window will open. If there have been several changes made, each will be identified through a timestamp.
   

   If you just want to revert to the immediate previous change, use the right-click option: Replace With > Previous from Local History...